On Fri, Oct 3, 2025, at 19:34, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <julia@jvns.ca>
>
> Git very often uses the terms "object", "reference", or "index" in its
> documentation.
>
> However, it's hard to find a clear explanation of these terms and how
> they relate to each other in the documentation. The closest candidates
> currently are:
>
> 1. `gitglossary`. This makes a good effort, but it's an alphabetically
>     ordered dictionary and a dictionary is not a good way to learn
>     concepts. You have to jump around too much and it's not possible to
>     present the concepts in the order that they should be explained.
> 2. `gitcore-tutorial`. This explains how to use the "core" Git commands.
>    This is a nice document to have, but it's not necessary to learn how
>    `update-index` works to understand Git's data model, and we should
>    not be requiring users to learn how to use the "plumbing" commands
>    if they want to learn what the term "index" or "object" means.
> 3. `gitrepository-layout`. This is a great resource, but it includes a
>    lot of information about configuration and internal implementation
>    details which are not related to the data model. It also does
>    not explain how commits work.
>
> The result of this is that Git users (even users who have been using
> Git for 15+ years) struggle to read the documentation because they don't
> know what the core terms mean, and it's not possible to add links
> to help them learn more.
>
> Add an explanation of Git's data model. Some choices I've made in
> deciding what "core data model" means:
>
> 1. Omit pseudorefs like `FETCH_HEAD`, because it's not clear to me
>    if those are intended to be user facing or if they're more like
>    internal implementation details.
> 2. Don't talk about submodules other than by mentioning how they
>    relate to trees. This is because Git has a lot of special features,
>    and explaining how they all work exhaustively could quickly go
>    down a rabbit hole which would make this document less useful for
>    understanding Git's core behaviour.
> 3. Don't discuss the structure of a commit message
>    (first line, trailers, GPG signatures, etc).
>    Perhaps this should change.
>
> Some other choices I've made:
>
> 1. Mention packed refs only in a note.

I don’t think it’s worth mentioning this at all.  More on that later.

> 2. Don't mention that the full name of the branch `main` is
>    technically `refs/heads/main`. This should likely change but I
>    haven't worked out how to do it in a clear way yet.

I think this is worth getting into.  This is a pretty
user-facing concept.

> 3. Mostly avoid referring to the `.git` directory, because the exact
>    details of how things are stored change over time.
>    This should perhaps change from "mostly" to "entirely"
>    but I haven't worked out how to do that in a clear way yet.

I think that’s good.  I mean, I think us users don’t need that level of
detail and shouldn’t be “inspired” to muck with the internals.  If that
makes sense.  (See later)

>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>     doc: Add a explanation of Git's data model
>[snip]
> diff --git a/Documentation/Makefile b/Documentation/Makefile
>[snip]
> diff --git a/Documentation/gitdatamodel.adoc
> b/Documentation/gitdatamodel.adoc
> new file mode 100644
> index 0000000000..4b2cb167dc
> --- /dev/null
> +++ b/Documentation/gitdatamodel.adoc
> @@ -0,0 +1,226 @@
> +gitdatamodel(7)
> +===============
> +
> +NAME
> +----
> +gitdatamodel - Git's core data model
> +
> +DESCRIPTION
> +-----------
> +
> +It's not necessary to understand Git's data model to use Git, but it's
> +very helpful when reading Git's documentation so that you know what it
> +means when the documentation says "object" "reference" or "index".

I haven’t gone hunting through the docs to see if this is covered
elsewhere.  But the thrust of all the things here definitely feel to me
like something that should be presented and documented in such a way.

> +
> +Git's core operations use 4 kinds of data:

Maybe small numerals should be spelled as words in running text?

> +
> +1. <<objects,Objects>>: commits, trees, blobs, and tag objects
> +2. <<references,References>>: branches, tags,
> +   remote-tracking branches, etc
> +3. <<index,The index>>, also known as the staging area
> +4. <<reflogs,Reflogs>>

Reflogs is certainly auxiliary ref data. What makes it qualify as
one-of-the-four?  I am open to it being both, to be clear.

> +
> +[[objects]]
> +OBJECTS
> +-------
> +
> +Commits, trees, blobs, and tag objects are all stored in Git's object
> database.
> +Every object has:
> +
> +1. an *ID*, which is the SHA-1 hash of its contents.
> +  It's fast to look up a Git object using its ID.
> +  The ID is usually represented in hexadecimal, like
> +  `1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a`.
> +2. a *type*. There are 4 types of objects:
> +   <<commit,commits>>, <<tree,trees>>, <<blob,blobs>>,
> +   and <<tag-object,tag objects>>.
> +3. *contents*. The structure of the contents depends on the type.
> +
> +Once an object is created, it can never be changed.
> +Here are the 4 types of objects:

As a curious Git user this seems correct.

> +
> +[[commit]]
> +commits::
> +    A commit contains:
> ++
> +1. Its *parent commit ID(s)*. The first commit in a repository has 0
> parents,

Maybe this is a subjective style thing but is it necessary to use “(s)”
when the context makes clear that it could be zero to many?

    Its *parent commit IDs. ...

> +  regular commits have 1 parent, merge commits have 2+ parents

s/2+/two or more/ ?

Same point as the “numeral” one above.

> +2. A *commit message*
> +3. All the *files* in the commit, stored as a *<<tree,tree>>*
> +4. An *author* and the time the commit was authored
> +5. A *committer* and the time the commit was committed
> ++
> +Here's how an example commit is stored:
> ++
> +----
> +tree 1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a
> +parent 4ccb6d7b8869a86aae2e84c56523f8705b50c647
> +author Maya <maya@example.com> 1759173425 -0400
> +committer Maya <maya@example.com> 1759173425 -0400
> +
> +Add README
> +----
> ++
> +Like all other objects, commits can never be changed after they're
> created.
> +For example, "amending" a commit with `git commit --amend` creates a
> new commit.

> +The old commit will eventually be deleted by `git gc`.

Maybe this could be moved to a part about what happens (eventually) to
unreachable objects?

Mentioning `git gc` and how things will get deleted raises
questions naturally. Like why would they be deleted? Okay
that’s clear: the previous commit will be replaced by the
amended one. Then when it is not reachable by anything
(even the reflog) it will get garbage collected.

It all follows. But is the reader necessarily mature enough
in their understanding to make the inference?

This is a long-winded way of saying: if you’re gonna discuss
`git gc` you might need to go into all of these concepts.

> +
> +[[tree]]
> +trees::
> +    A tree is how Git represents a directory. It lists, for each item
> in
> +    the tree:
> ++
> +1. The *permissions*, for example `100644`
> +2. The *type*: either <<blob,`blob`>> (a file), `tree` (a directory),
> +  or <<commit,`commit`>> (a Git submodule)
> +3. The *object ID*
> +4. The *filename*
> ++
> +For example, this is how a tree containing one directory (`src`) and
> one file
> +(`README.md`) is stored:
> ++
> +----
> +100644 blob 8728a858d9d21a8c78488c8b4e70e531b659141f README.md
> +040000 tree 89b1d2e0495f66d6929f4ff76ff1bb07fc41947d src
> +----
> ++
> +*NOTE:* The permissions are in the same format as UNIX permissions, but
> +the only allowed permissions for files (blobs) are 644 and 755.
> +

Makes sense.

> +[[blob]]
> +blobs::
> +    A blob is how Git represents a file. A blob object contains the
> +    file's contents.
> ++
> +Storing a new blob for every new version of a file can get big, so
> +`git gc` periodically compresses objects for efficiency in
> `.git/objects/pack`.

This gets into mentioning implementation files(?) like you mentioned in
the commit message.

1. That it’s a packfile and where it is might be too much detail for
   this doc
2. I vaguely recall documents discussing what happens to “storing every
   version” discussing deltas instead of packs? Again, I am not a Git
   developer though.

> +
> +[[tag-object]]
> +tag objects::
> +    Tag objects (also known as "annotated tags") contain:
> ++
> +1. The *tagger* and tag date
> +2. A *tag message*, similar to a commit message
> +3. The *ID* of the object (often a commit) that they reference

s/often/typically/ ?

I know it can get tedious to caveat the 99% cases with things that are
technically possible.  Maybe if it gets “bad enough” there could be a
part that explains/distinguishes the high-level/porcelain Git use and
what is technically possible: you make a `git tag -a`, which is on a
commit... except if you accidentally run it on top of an existing
tag. Then even the porcelain won’t protect you from making a 
tag-on-tag. (But it will issue a warning I guess.) Hmm. Now I don’t know.

> +
> +[[references]]
> +REFERENCES
> +----------
> +
> +References are a way to give a name to a commit.
> +It's easier to remember "the changes I'm working on are on the `turtle`
> +branch" than "the changes are in commit bb69721404348e".
> +Git often uses "ref" as shorthand for "reference".

Good.

> +
> +References that you create are stored in the `.git/refs` directory,
> +and Git has a few special internal references like `HEAD` that are
> stored
> +in the base `.git` directory.

Implementation file details.

You also mention `.git/refs/heads/<name>` below.  But refs aren’t stored
as files if you are using the *reftable* backend.  And that backend will
become the default for new repositories in Git 3.0, I think.

How does reftable work?  I don’t know.  But I don’t think we need to
know after reading this doc. :)

To be clear: how files are stored might not matter here.

> +
> +References can either be:
> +
> +1. References to an object ID, usually a <<commit,commit>> ID
> +2. References to another reference. This is called a "symbolic
> reference".

You seem to have used `**` when introducing terms:

    This is a *symbolic reference*

>[snip ref stuff]
> +
> +[[HEAD]]
> +HEAD: `.git/HEAD`::
> +    `HEAD` is where Git stores your current <<branch,branch>>.
> +    `HEAD` is normally a symbolic reference to your current branch, for
> +    example `ref: refs/heads/main` if your current branch is `main`.
> +    `HEAD` can also be a direct reference to a commit ID,
> +    that's called "detached HEAD state".
> +
> +[[remote-tracking-branch]]
> +remote tracking branches: `.git/refs/remotes/<remote>/<branch>`::
> +    A remote-tracking branch is a name for a commit ID.
> +    It's how Git stores the last-known state of a branch in a remote
> +    repository. `git fetch` updates remote-tracking branches. When
> +    `git status` says "you're up to date with origin/main", it's looking at
> +    this.

Looks good.

> +
> +[[other-refs]]
> +Other references::
> +    Git tools may create references in any subdirectory of `.git/refs`.
> +    For example, linkgit:git-stash[1], linkgit:git-bisect[1],
> +    and linkgit:git-notes[1] all create their own references
> +    in `.git/refs/stash`, `.git/refs/bisect`, etc.
> +    Third-party Git tools may also create their own references.
> ++
> +Git may also create references in the base `.git` directory
> +other than `HEAD`, like `ORIG_HEAD`.
> +

> +*NOTE:* As an optimization, references may be stored as packed
> +refs instead of in `.git/refs`. See linkgit:git-pack-refs[1].

I don’t know if this is relevant for both ref backends. And does it
matter?

> +
> +[[index]]
> +THE INDEX
> +---------
> +
> +The index, also known as the "staging area", contains the current
> staged
> +version of every file in your Git repository. When you commit, the
> files
> +in the index are used as the files in the next commit.
> +
> +Unlike a tree, the index is a flat list of files.
> +Each index entry has 4 fields:
> +
> +1. The *permissions*
> +2. The *<<blob,blob>> ID* of the file
> +3. The *filename*
> +4. The *number*. This is normally 0, but if there's a merge conflict
> +   there can be multiple versions (with numbers 0, 1, 2, ..)
> +   of the same filename in the index.
> +
> +It's extremely uncommon to look at the index directly: normally you'd
> +run `git status` to see a list of changes between the index and
> <<HEAD,HEAD>>.
> +But you can use `git ls-files --stage` to see the index.
> +Here's the output of `git ls-files --stage` in a repository with 2
> files:
> +
> +----
> +100644 8728a858d9d21a8c78488c8b4e70e531b659141f 0 README.md
> +100644 665c637a360874ce43bf74018768a96d2d4d219a 0 src/hello.py
> +----
> +
> +[[reflogs]]
> +REFLOGS
> +-------
> +
> +Git stores the history of branch, tag, and HEAD refs in a reflog
> +(you should read "reflog" as "ref log"). Not every ref is logged by

You’ve heard of the re-flog too?

> +default, but any ref can be logged.
> +
> +Each reflog entry has:
> +
> +1. *Before/after *commit IDs*
> +2. *User* who made the change, for example `Maya <maya@example.com>`
> +3. *Timestamp*
> +4. *Log message*, for example `pull: Fast-forward`
> +
> +Reflogs only log changes made in your local repository.
> +They are not shared with remotes.

Makes sense.

> +
> +GIT
> +---
> +Part of the linkgit:git[1] suite

I appreciate that this is the first version and you might have plans
after this one. But I wonder if this doc could use a fair number of
`gitlink` to branch out to all the other parts. Like git-reflog(1),
gitglossary(7).

Thanks for starting on a whole new doc. That must take quite
some effort.

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> +MAN7_TXT += gitdatamodel.adoc
>  MAN7_TXT += gitdiffcore.adoc
> ...
> +gitdatamodel(7)
> +===============
> +
> +NAME
> +----
> +gitdatamodel - Git's core data model
> +
> +DESCRIPTION
> +-----------

The above causes doc-lint to barf.

https://github.com/git/git/actions/runs/18265502271/job/51999236907#step:4:655

gitdatamodel.adoc:226: has no required 'SYNOPSIS' section!
    LINT MAN SEC giteveryday.adoc
make[1]: *** [Makefile:498: .build/lint-docs/man-section-order/gitdatamodel.ok] Error 1


You can check locally with "make check-docs" without waiting for my
integration cycle to push to GitHub CI.

Thanks.

> The above causes doc-lint to barf.
>
> https://github.com/git/git/actions/runs/18265502271/job/51999236907#step:4:655
>
> gitdatamodel.adoc:226: has no required 'SYNOPSIS' section!
>     LINT MAN SEC giteveryday.adoc
> make[1]: *** [Makefile:498: 
> .build/lint-docs/man-section-order/gitdatamodel.ok] Error 1
>
>
> You can check locally with "make check-docs" without waiting for my
> integration cycle to push to GitHub CI.


Thanks, will fix.

Thanks for the review!

>> 2. Don't mention that the full name of the branch `main` is
>>    technically `refs/heads/main`. This should likely change but I
>>    haven't worked out how to do it in a clear way yet.
>
> I think this is worth getting into.  This is a pretty
> user-facing concept.

I think I'll see if I can figure out a way to mention this and at the
same time remove most of the rest of the references to the `.git`
directory when explaining references (which you talked about
further down), including packed refs.

>> +
>> +1. <<objects,Objects>>: commits, trees, blobs, and tag objects
>> +2. <<references,References>>: branches, tags,
>> +   remote-tracking branches, etc
>> +3. <<index,The index>>, also known as the staging area
>> +4. <<reflogs,Reflogs>>
>
> Reflogs is certainly auxiliary ref data. What makes it qualify as
> one-of-the-four?  I am open to it being both, to be clear.

The reason I like to talk about reflogs is that it gives you a
way to "undo" Git operations that can be really useful. 
And any Git command that updates refs can updates that
ref's reflog.

Understanding how reflogs work helps to understand what the
limitations of using reflogs to undo mistakes is: for example
the index is not a ref, so you can't use the reflog to undo
changes to the index.

>> +2. A *commit message*
>> +3. All the *files* in the commit, stored as a *<<tree,tree>>*
>> +4. An *author* and the time the commit was authored
>> +5. A *committer* and the time the commit was committed
>> ++
>> +Here's how an example commit is stored:
>> ++
>> +----
>> +tree 1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a
>> +parent 4ccb6d7b8869a86aae2e84c56523f8705b50c647
>> +author Maya <maya@example.com> 1759173425 -0400
>> +committer Maya <maya@example.com> 1759173425 -0400
>> +
>> +Add README
>> +----
>> ++
>> +Like all other objects, commits can never be changed after they're
>> created.
>> +For example, "amending" a commit with `git commit --amend` creates a
>> new commit.
>
>> +The old commit will eventually be deleted by `git gc`.
>
> Maybe this could be moved to a part about what happens (eventually) to
> unreachable objects?
>
> Mentioning `git gc` and how things will get deleted raises
> questions naturally. Like why would they be deleted? Okay
> that’s clear: the previous commit will be replaced by the
> amended one. Then when it is not reachable by anything
> (even the reflog) it will get garbage collected.
>
> It all follows. But is the reader necessarily mature enough
> in their understanding to make the inference?
>
> This is a long-winded way of saying: if you’re gonna discuss
> `git gc` you might need to go into all of these concepts.

If folks here think this is a reasonable document to add to
Git I'll try get some beta readers to read this, see which parts
folks find confusing, and address those, keeping the `git gc`
stuff in mind.

Similarly for the style comments.

>> +blobs::
>> +    A blob is how Git represents a file. A blob object contains the
>> +    file's contents.
>> ++
>> +Storing a new blob for every new version of a file can get big, so
>> +`git gc` periodically compresses objects for efficiency in
>> `.git/objects/pack`.
>
> This gets into mentioning implementation files(?) like you mentioned in
> the commit message.

That's true! The reason I think this is important to mention is that I find
that people often "reject" information that they find implausible, even
if it comes from a credible source. ("that can't be true! I must be
not understanding correctly. Oh well, I'll just ignore that!")

I sometimes hear from users that "commits can't be snapshots", because
it would take up too much disk space to store every version of
every commit. So I find that sometimes explaining a little bit about the
implementation can make the information more memorable.

Certainly I'm not able to remember details that don't make sense
with my mental model of how computers work and I don't expect other
people to either, so I think it's important to give an explanation that
handles the biggest "objections".

> 1. That it’s a packfile and where it is might be too much detail for
>    this doc
> 2. I vaguely recall documents discussing what happens to “storing every
>    version” discussing deltas instead of packs? Again, I am not a Git
>    developer though.

I could be wrong about the details here, I'm not a Git developer either.
From https://git-scm.com/book/en/v2/Git-Internals-Packfiles
it looks like packfiles are implemented using deltas.

>> +
>> +References can either be:
>> +
>> +1. References to an object ID, usually a <<commit,commit>> ID
>> +2. References to another reference. This is called a "symbolic
>> reference".
>
> You seem to have used `**` when introducing terms:
>
>     This is a *symbolic reference*

Thanks, will take a look at that.

>> +[[reflogs]]
>> +REFLOGS
>> +-------
>> +
>> +Git stores the history of branch, tag, and HEAD refs in a reflog
>> +(you should read "reflog" as "ref log"). Not every ref is logged by
>
> You’ve heard of the re-flog too?

haha exactly, I just want folks to understand why it's called that :)

> I appreciate that this is the first version and you might have plans
> after this one. But I wonder if this doc could use a fair number of
> `gitlink` to branch out to all the other parts. Like git-reflog(1),
> gitglossary(7).

That's reasonable. Do you often use the "See also" section of
man pages? I've never looked at them so I'm always curious about
how people are actually using them in practice.

I also need to think about what else could link *to* this, because
without attention to discoverability probably nobody will find it.
My main idea so far is actually to add it to
https://git-scm.com/learn
but I wanted to send it here instead of adding it to the website
directly because I thought it could benefit from a more detailed
review.

> Thanks for starting on a whole new doc. That must take quite
> some effort.

All the work on documentation takes a lot of effort, in some
ways it's easier to write something new than to edit something
existing :)

On Mon, Oct 6, 2025 at 3:37 PM Julia Evans <julia@jvns.ca> wrote:
>
> Thanks for the review!
>
> >> 2. Don't mention that the full name of the branch `main` is
> >>    technically `refs/heads/main`. This should likely change but I
> >>    haven't worked out how to do it in a clear way yet.
> >
> > I think this is worth getting into.  This is a pretty
> > user-facing concept.
>
> I think I'll see if I can figure out a way to mention this and at the
> same time remove most of the rest of the references to the `.git`
> directory when explaining references (which you talked about
> further down), including packed refs.

A colleague will be explaining reflog for an audience tomorrow, and
decided to briefly explain refs, too—which tells me this is
much-needed.

For refs themselves, perhaps "git for-each-ref" is a reasonable place
to start? Since it tells you the refs you have and how to spell them
explicitly regardless of how they are stored?

-- 
D. Ben Knoble

On Mon, Oct 6, 2025, at 5:44 PM, D. Ben Knoble wrote:
> On Mon, Oct 6, 2025 at 3:37 PM Julia Evans <julia@jvns.ca> wrote:
>>
>> Thanks for the review!
>>
>> >> 2. Don't mention that the full name of the branch `main` is
>> >>    technically `refs/heads/main`. This should likely change but I
>> >>    haven't worked out how to do it in a clear way yet.
>> >
>> > I think this is worth getting into.  This is a pretty
>> > user-facing concept.
>>
>> I think I'll see if I can figure out a way to mention this and at the
>> same time remove most of the rest of the references to the `.git`
>> directory when explaining references (which you talked about
>> further down), including packed refs.
>
> A colleague will be explaining reflog for an audience tomorrow, and
> decided to briefly explain refs, too—which tells me this is
> much-needed.
>
> For refs themselves, perhaps "git for-each-ref" is a reasonable place
> to start? Since it tells you the refs you have and how to spell them
> explicitly regardless of how they are stored?

Interesting, do you use git for-each-ref? 
What do you use it for?

> -- 
> D. Ben Knoble

On Mon, Oct 6, 2025 at 5:47 PM Julia Evans <julia@jvns.ca> wrote:
>
>
>
> On Mon, Oct 6, 2025, at 5:44 PM, D. Ben Knoble wrote:
> > On Mon, Oct 6, 2025 at 3:37 PM Julia Evans <julia@jvns.ca> wrote:
> >>
> >> Thanks for the review!
> >>
> >> >> 2. Don't mention that the full name of the branch `main` is
> >> >>    technically `refs/heads/main`. This should likely change but I
> >> >>    haven't worked out how to do it in a clear way yet.
> >> >
> >> > I think this is worth getting into.  This is a pretty
> >> > user-facing concept.
> >>
> >> I think I'll see if I can figure out a way to mention this and at the
> >> same time remove most of the rest of the references to the `.git`
> >> directory when explaining references (which you talked about
> >> further down), including packed refs.
> >
> > A colleague will be explaining reflog for an audience tomorrow, and
> > decided to briefly explain refs, too—which tells me this is
> > much-needed.
> >
> > For refs themselves, perhaps "git for-each-ref" is a reasonable place
> > to start? Since it tells you the refs you have and how to spell them
> > explicitly regardless of how they are stored?
>
> Interesting, do you use git for-each-ref?
> What do you use it for?

Ah, yes, but primarily for scripting.

What I should have clarified is that "the tool (I know of) to
interrogate the refs you currently have is git-for-each-ref" (like how
git-ls-remote is the tool to interrogate a remote's refs). It avoids
the issues with assuming "tree .git/refs" or similar will capture the
actual data.

-- 
D. Ben Knoble

On Mon, Oct 6, 2025, at 05:32, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> +MAN7_TXT += gitdatamodel.adoc
>>  MAN7_TXT += gitdiffcore.adoc
>> ...
>> +gitdatamodel(7)
>> +===============
>> +
>> +NAME
>> +----
>> +gitdatamodel - Git's core data model
>> +
>> +DESCRIPTION
>> +-----------
>
> The above causes doc-lint to barf.
>[snip]
> You can check locally with "make check-docs" without waiting for my
> integration cycle to push to GitHub CI.

I think you meant `make lint-docs` for both of these.

On Fri, Oct 03, 2025 at 05:34:36PM +0000, Julia Evans via GitGitGadget wrote:
> diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
> new file mode 100644
> index 0000000000..4b2cb167dc
> --- /dev/null
> +++ b/Documentation/gitdatamodel.adoc
> @@ -0,0 +1,226 @@
> +gitdatamodel(7)
> +===============
> +
> +NAME
> +----
> +gitdatamodel - Git's core data model
> +
> +DESCRIPTION
> +-----------
> +
> +It's not necessary to understand Git's data model to use Git, but it's
> +very helpful when reading Git's documentation so that you know what it
> +means when the documentation says "object" "reference" or "index".

There's a missing comma after "object".

> +
> +Git's core operations use 4 kinds of data:
> +
> +1. <<objects,Objects>>: commits, trees, blobs, and tag objects
> +2. <<references,References>>: branches, tags,
> +   remote-tracking branches, etc
> +3. <<index,The index>>, also known as the staging area
> +4. <<reflogs,Reflogs>>

This list makes sense to me. There's of course more data structures in
Git, but all the other data structures shouldn't really matter to users
at all as they are mostly caches or internal details of the on-disk
format.

There's potentially one exception though, namely the Git configuration.
I'd claim that Git "uses" the Git configuration similarly to how it uses
the others, but I get why it's not explicitly mentioned here.

> +[[objects]]
> +OBJECTS
> +-------
> +
> +Commits, trees, blobs, and tag objects are all stored in Git's object database.
> +Every object has:
> +
> +1. an *ID*, which is the SHA-1 hash of its contents.

I think this needs to be adapted to not single out SHA-1 as the only
hashing algorithm. We already support SHA-256, so we should definitely
say that the algorithm can be swapped. Maybe something like:

  An *object ID*, which is the cryptographic hash of its contents. By
  default, Git uses SHA-1 as object hash, but alternative hashes like
  SHA-256 are supported.

> +  It's fast to look up a Git object using its ID.
> +  The ID is usually represented in hexadecimal, like
> +  `1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a`.
> +2. a *type*. There are 4 types of objects:
> +   <<commit,commits>>, <<tree,trees>>, <<blob,blobs>>,
> +   and <<tag-object,tag objects>>.
> +3. *contents*. The structure of the contents depends on the type.

Nit: every object also has an object size. Not sure though whether it's
fine to imply that with "contents".

> +Once an object is created, it can never be changed.
> +Here are the 4 types of objects:
> +
> +[[commit]]
> +commits::
> +    A commit contains:
> ++
> +1. Its *parent commit ID(s)*. The first commit in a repository has 0 parents,
> +  regular commits have 1 parent, merge commits have 2+ parents

I'd say "at least two parents" instead of "2+ parents".

> +2. A *commit message*
> +3. All the *files* in the commit, stored as a *<<tree,tree>>*
> +4. An *author* and the time the commit was authored
> +5. A *committer* and the time the commit was committed
> ++
> +Here's how an example commit is stored:
> ++
> +----
> +tree 1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a
> +parent 4ccb6d7b8869a86aae2e84c56523f8705b50c647
> +author Maya <maya@example.com> 1759173425 -0400
> +committer Maya <maya@example.com> 1759173425 -0400
> +
> +Add README
> +----

In practice, commits can have other headers that are ignored by Git. But
that's certainly not part of Git's core data model, so I don't think we
should mention that here.

> +Like all other objects, commits can never be changed after they're created.
> +For example, "amending" a commit with `git commit --amend` creates a new commit.
> +The old commit will eventually be deleted by `git gc`.

If we mention git-gc(1) I think it would make sense to use
`linkgit:git-gc[1]` instead to provide a link to its man page.

> +[[tree]]
> +trees::
> +    A tree is how Git represents a directory. It lists, for each item in
> +    the tree:
> ++
> +1. The *permissions*, for example `100644`

I think we should rather call these "mode bits". These bits are
permissions indeed when you have a blob, but for subtrees, symlinks and
submodules they aren't.

> +2. The *type*: either <<blob,`blob`>> (a file), `tree` (a directory),
> +  or <<commit,`commit`>> (a Git submodule)

There's also symlinks.

> +3. The *object ID*
> +4. The *filename*
> ++
> +For example, this is how a tree containing one directory (`src`) and one file
> +(`README.md`) is stored:
> ++
> +----
> +100644 blob 8728a858d9d21a8c78488c8b4e70e531b659141f README.md
> +040000 tree 89b1d2e0495f66d6929f4ff76ff1bb07fc41947d src
> +----
> ++
> +*NOTE:* The permissions are in the same format as UNIX permissions, but
> +the only allowed permissions for files (blobs) are 644 and 755.
> +
> +[[blob]]
> +blobs::
> +    A blob is how Git represents a file. A blob object contains the
> +    file's contents.
> ++
> +Storing a new blob for every new version of a file can get big, so
> +`git gc` periodically compresses objects for efficiency in `.git/objects/pack`.

I would claim that it's not necessary to mention object compression.
This should be a low-level detail that users don't ever have to worry
about. Furthermore, packing objects isn't only relevant in the context
of blobs: trees for example also tend to compress very well as there
typically is only small incremental updates to trees.

> +[[tag-object]]
> +tag objects::
> +    Tag objects (also known as "annotated tags") contain:
> ++
> +1. The *tagger* and tag date
> +2. A *tag message*, similar to a commit message
> +3. The *ID* of the object (often a commit) that they reference

They can also be signed, if we want to mention that.

> +[[references]]
> +REFERENCES
> +----------
> +
> +References are a way to give a name to a commit.
> +It's easier to remember "the changes I'm working on are on the `turtle`
> +branch" than "the changes are in commit bb69721404348e".
> +Git often uses "ref" as shorthand for "reference".
> +
> +References that you create are stored in the `.git/refs` directory,
> +and Git has a few special internal references like `HEAD` that are stored
> +in the base `.git` directory.

This isn't true anymore with the introduction of the reftable backend,
which is slated to become the default backend. I'd argue that this is
another implementation detail that the user shouldn't have to worry
about.

> +References can either be:
> +
> +1. References to an object ID, usually a <<commit,commit>> ID
> +2. References to another reference. This is called a "symbolic reference".
> +
> +Git handles references differently based on which subdirectory of
> +`.git/refs` they're stored in.

So instead of saying "subdirectory", I'd rather say "reference
hierarchy".

In general, I think we should explain that references are layed out
in a hierarchy. This is somewhat obvious with the "files" backend, as we
use directories there. But as we move on to the "reftable" backend this
may become less obvious over time.

> +Here are the main types:
> +
> +[[branch]]
> +branches: `.git/refs/heads/<name>`::

Here and in the other cases we should then strip the `.git/` prefix.

> +    A branch is a name for a commit ID.
> +    That commit is the latest commit on the branch.
> +    Branches are stored in the `.git/refs/heads/` directory.
> ++
> +To get the history of commits on a branch, Git will start at the commit
> +ID the branch references, and then look at the commit's parent(s),
> +the parent's parent, etc.
> +
> +[[tag]]
> +tags: `.git/refs/tags/<name>`::
> +    A tag is a name for a commit ID, tag object ID, or other object ID.
> +    Tags are stored in the `refs/tags/` directory.
> ++
> +Even though branches and commits are both "a name for a commit ID", Git
> +treats them very differently.
> +Branches are expected to be regularly updated as you work on the branch,
> +but it's expected that a tag will never change after you create it.

This sounds a bit like the user itself needs to update the branch. How
about this instead:

    Even though branches and commits are both "a name for a commit ID", Git
    treats them very differently:

        - Branches can be checked out directly. If so, creating a new
          commit will automatically update the checked-out branch to
          point to the new commit.

        - Tags cannot be checked out directly and don't move when
          creating a new commit. Instead, one can only check out the
          commit that a branch points to. This is called "detached
          HEAD", and the effect is that a new commit will not update 

> +[[HEAD]]
> +HEAD: `.git/HEAD`::
> +    `HEAD` is where Git stores your current <<branch,branch>>.
> +    `HEAD` is normally a symbolic reference to your current branch, for
> +    example `ref: refs/heads/main` if your current branch is `main`.
> +    `HEAD` can also be a direct reference to a commit ID,
> +    that's called "detached HEAD state".
> +
> +[[remote-tracking-branch]]
> +remote tracking branches: `.git/refs/remotes/<remote>/<branch>`::
> +    A remote-tracking branch is a name for a commit ID.
> +    It's how Git stores the last-known state of a branch in a remote
> +    repository. `git fetch` updates remote-tracking branches. When
> +    `git status` says "you're up to date with origin/main", it's looking at
> +    this.

This misses "refs/remotes/<remote>/HEAD". This reference is a symbolic
reference that indicates the default branch on the remote side.

> +[[other-refs]]
> +Other references::
> +    Git tools may create references in any subdirectory of `.git/refs`.
> +    For example, linkgit:git-stash[1], linkgit:git-bisect[1],
> +    and linkgit:git-notes[1] all create their own references
> +    in `.git/refs/stash`, `.git/refs/bisect`, etc.
> +    Third-party Git tools may also create their own references.
> ++
> +Git may also create references in the base `.git` directory
> +other than `HEAD`, like `ORIG_HEAD`.

Let's mention that such references are typically spelt all-uppercase
with underscores between. You shouldn't ever create a reference that is
for example called ".git/foo".

We enforce this restriction inconsistently, only, but I don't think that
should keep us from spelling out the common rule.

> +*NOTE:* As an optimization, references may be stored as packed
> +refs instead of in `.git/refs`. See linkgit:git-pack-refs[1].

I'd drop this note. It's an internal implementation detail and only true
for the "files" backend. The "reftable" backend stores references quite
differently and doesn't really "pack" references.

> +[[index]]
> +THE INDEX
> +---------
> +
> +The index, also known as the "staging area", contains the current staged

Honestly, I always forget which of these two nouns we are supposed to
use nowadays. I think consensus was to use "index" and avoid using
"staging area"? Not sure though, but I think we should only mention
one of these.

> +version of every file in your Git repository. When you commit, the files
> +in the index are used as the files in the next commit.
> +
> +Unlike a tree, the index is a flat list of files.
> +Each index entry has 4 fields:
> +
> +1. The *permissions*
> +2. The *<<blob,blob>> ID* of the file
> +3. The *filename*
> +4. The *number*. This is normally 0, but if there's a merge conflict

I think we don't call this "number", but "stage".

> +   there can be multiple versions (with numbers 0, 1, 2, ..)
> +   of the same filename in the index.
> +
> +It's extremely uncommon to look at the index directly: normally you'd
> +run `git status` to see a list of changes between the index and <<HEAD,HEAD>>.
> +But you can use `git ls-files --stage` to see the index.
> +Here's the output of `git ls-files --stage` in a repository with 2 files:
> +
> +----
> +100644 8728a858d9d21a8c78488c8b4e70e531b659141f 0 README.md
> +100644 665c637a360874ce43bf74018768a96d2d4d219a 0 src/hello.py
> +----
> +
> +[[reflogs]]
> +REFLOGS
> +-------
> +
> +Git stores the history of branch, tag, and HEAD refs in a reflog
> +(you should read "reflog" as "ref log"). Not every ref is logged by
> +default, but any ref can be logged.

If we mention this here, do we maybe want to mention how the user can
decide which references are logged?

> +Each reflog entry has:
> +
> +1. *Before/after *commit IDs*

This will probably misformat as we have three asterisks here, not two.

> +2. *User* who made the change, for example `Maya <maya@example.com>`
> +3. *Timestamp*

Suggestion: "*Timestamp* when that change has been made".

> +4. *Log message*, for example `pull: Fast-forward`
> +
> +Reflogs only log changes made in your local repository.
> +They are not shared with remotes.

We may want ot mention that you can reference reflog entries via
`refs/heads/<branch>@{<reflog-nr>}`.

In general, one thing that I think would be important to highlight in
this document is revisions. Most of the commands tend to not accept
references, but revisions instead, which are a lot more flexible. They
use our do-what-I-mean mechanism to resolve, but also allow the user to
specify commits relative to one another. It's probably sufficient though
to mention them briefly and then redirect to girevisions(7).

Thanks for working on this!

Patrick

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> On Mon, Oct 6, 2025, at 05:32, Junio C Hamano wrote:
>> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>>
>>> +MAN7_TXT += gitdatamodel.adoc
>>>  MAN7_TXT += gitdiffcore.adoc
>>> ...
>>> +gitdatamodel(7)
>>> +===============
>>> +
>>> +NAME
>>> +----
>>> +gitdatamodel - Git's core data model
>>> +
>>> +DESCRIPTION
>>> +-----------
>>
>> The above causes doc-lint to barf.
>>[snip]
>> You can check locally with "make check-docs" without waiting for my
>> integration cycle to push to GitHub CI.
>
> I think you meant `make lint-docs` for both of these.

The former is a typo for "causes lint-docs to barf", but I did mean
"make check-docs" as the recipe for local checking.

You could also do "make -C Documentation lint-docs", but that is a
lot more to type ;-).

Thanks.

Patrick Steinhardt <ps@pks.im> writes:

>> +Git's core operations use 4 kinds of data:
>> +
>> +1. <<objects,Objects>>: commits, trees, blobs, and tag objects
>> +2. <<references,References>>: branches, tags,
>> +   remote-tracking branches, etc
>> +3. <<index,The index>>, also known as the staging area
>> +4. <<reflogs,Reflogs>>
>
> This list makes sense to me. There's of course more data structures in
> Git, but all the other data structures shouldn't really matter to users
> at all as they are mostly caches or internal details of the on-disk
> format.
>
> There's potentially one exception though, namely the Git configuration.
> I'd claim that Git "uses" the Git configuration similarly to how it uses
> the others, but I get why it's not explicitly mentioned here.

The core operations do not use Git configuration any more than they
use what is specified by the command line arguments.

>> +[[objects]]
>> +OBJECTS
>> +-------
>> +
>> +Commits, trees, blobs, and tag objects are all stored in Git's object database.
>> +Every object has:
>> +
>> +1. an *ID*, which is the SHA-1 hash of its contents.
>
> I think this needs to be adapted to not single out SHA-1 as the only
> hashing algorithm. We already support SHA-256, so we should definitely
> say that the algorithm can be swapped. Maybe something like:

Good point.  Also officially they are called "object name".

>   An *object ID*, which is the cryptographic hash of its contents. By
>   default, Git uses SHA-1 as object hash, but alternative hashes like
>   SHA-256 are supported.

I'd avoid "object name is the result of hashing X" which historically
was a source of question: "why does 'sha1sum README.md' give different
hash from 'git add README.md && git ls-files -s README.md'?"

It is an irrelevant implementation detail (and you'd eventually end
up having to say "X is <type> SP <length> NUL <contents>").

    An object name, which is derived cryptographically from its
    type, size and contents.  All versions of Git can use SHA-1 hash
    function, but more recent versions of Git can also use SHA-256
    hash function.

>> +commits::
>> +    A commit contains:
>> ++
>> +1. Its *parent commit ID(s)*. The first commit in a repository has 0 parents,
>> +  regular commits have 1 parent, merge commits have 2+ parents
>
> I'd say "at least two parents" instead of "2+ parents".

Yup, that reads much better.

>> +tree 1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a
>> +parent 4ccb6d7b8869a86aae2e84c56523f8705b50c647
>> +author Maya <maya@example.com> 1759173425 -0400
>> +committer Maya <maya@example.com> 1759173425 -0400
>> +
>> +Add README
>> +----
>
> In practice, commits can have other headers that are ignored by Git. But
> that's certainly not part of Git's core data model, so I don't think we
> should mention that here.

Third-party software can add truly garbage ones that do not have any
meaning, and Git tolerates by ignoring them.  But there are others
that Git does pay attention to, like encoding, gpgsig, etc., which
may worth mention (in the form that "these four are what you typically
see, but there may be others" without even naming any).

On Tue, Oct 7, 2025 at 11:51 AM Patrick Steinhardt <ps@pks.im> wrote:
>
> On Fri, Oct 03, 2025 at 05:34:36PM +0000, Julia Evans via GitGitGadget wrote:
[snip]
> > +    A branch is a name for a commit ID.
> > +    That commit is the latest commit on the branch.
> > +    Branches are stored in the `.git/refs/heads/` directory.
> > ++
> > +To get the history of commits on a branch, Git will start at the commit
> > +ID the branch references, and then look at the commit's parent(s),
> > +the parent's parent, etc.
> > +
> > +[[tag]]
> > +tags: `.git/refs/tags/<name>`::
> > +    A tag is a name for a commit ID, tag object ID, or other object ID.
> > +    Tags are stored in the `refs/tags/` directory.
> > ++
> > +Even though branches and commits are both "a name for a commit ID", Git
> > +treats them very differently.
> > +Branches are expected to be regularly updated as you work on the branch,
> > +but it's expected that a tag will never change after you create it.
>
> This sounds a bit like the user itself needs to update the branch. How
> about this instead:
>
>     Even though branches and commits are both "a name for a commit ID", Git
>     treats them very differently:
>
>         - Branches can be checked out directly. If so, creating a new
>           commit will automatically update the checked-out branch to
>           point to the new commit.
>
>         - Tags cannot be checked out directly and don't move when
>           creating a new commit. Instead, one can only check out the
>           commit that a branch points to. This is called "detached
>           HEAD", and the effect is that a new commit will not update

missing "the tag." ?

On Tue, Oct 7, 2025, at 10:32 AM, Patrick Steinhardt wrote:
> On Fri, Oct 03, 2025 at 05:34:36PM +0000, Julia Evans via GitGitGadget wrote:
>> diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
>> new file mode 100644
>> index 0000000000..4b2cb167dc
>> --- /dev/null
>> +++ b/Documentation/gitdatamodel.adoc
>> @@ -0,0 +1,226 @@
>> +gitdatamodel(7)
>> +===============
>> +
>> +NAME
>> +----
>> +gitdatamodel - Git's core data model
>> +
>> +DESCRIPTION
>> +-----------
>> +
>> +It's not necessary to understand Git's data model to use Git, but it's
>> +very helpful when reading Git's documentation so that you know what it
>> +means when the documentation says "object" "reference" or "index".
>
> There's a missing comma after "object".

Will fix.

>> +
>> +Git's core operations use 4 kinds of data:
>> +
>> +1. <<objects,Objects>>: commits, trees, blobs, and tag objects
>> +2. <<references,References>>: branches, tags,
>> +   remote-tracking branches, etc
>> +3. <<index,The index>>, also known as the staging area
>> +4. <<reflogs,Reflogs>>
>
> This list makes sense to me. There's of course more data structures in
> Git, but all the other data structures shouldn't really matter to users
> at all as they are mostly caches or internal details of the on-disk
> format.
>
> There's potentially one exception though, namely the Git configuration.
> I'd claim that Git "uses" the Git configuration similarly to how it uses
> the others, but I get why it's not explicitly mentioned here.
>
>> +[[objects]]
>> +OBJECTS
>> +-------
>> +
>> +Commits, trees, blobs, and tag objects are all stored in Git's object database.
>> +Every object has:
>> +
>> +1. an *ID*, which is the SHA-1 hash of its contents.
>
> I think this needs to be adapted to not single out SHA-1 as the only
> hashing algorithm. We already support SHA-256, so we should definitely
> say that the algorithm can be swapped. Maybe something like:
>
>   An *object ID*, which is the cryptographic hash of its contents. By
>   default, Git uses SHA-1 as object hash, but alternative hashes like
>   SHA-256 are supported.

Makes sense. I might just say "cryptographic hash of its type and contents"
and leave it that. I'm not sure it's worth getting into details
of the exact hash function.

>> +  It's fast to look up a Git object using its ID.
>> +  The ID is usually represented in hexadecimal, like
>> +  `1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a`.
>> +2. a *type*. There are 4 types of objects:
>> +   <<commit,commits>>, <<tree,trees>>, <<blob,blobs>>,
>> +   and <<tag-object,tag objects>>.
>> +3. *contents*. The structure of the contents depends on the type.
>
> Nit: every object also has an object size. Not sure though whether it's
> fine to imply that with "contents".

I think it is.

>> +Once an object is created, it can never be changed.
>> +Here are the 4 types of objects:
>> +
>> +[[commit]]
>> +commits::
>> +    A commit contains:
>> ++
>> +1. Its *parent commit ID(s)*. The first commit in a repository has 0 parents,
>> +  regular commits have 1 parent, merge commits have 2+ parents
>
> I'd say "at least two parents" instead of "2+ parents".
>
>> +2. A *commit message*
>> +3. All the *files* in the commit, stored as a *<<tree,tree>>*
>> +4. An *author* and the time the commit was authored
>> +5. A *committer* and the time the commit was committed
>> ++
>> +Here's how an example commit is stored:
>> ++
>> +----
>> +tree 1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a
>> +parent 4ccb6d7b8869a86aae2e84c56523f8705b50c647
>> +author Maya <maya@example.com> 1759173425 -0400
>> +committer Maya <maya@example.com> 1759173425 -0400
>> +
>> +Add README
>> +----
>
> In practice, commits can have other headers that are ignored by Git. But
> that's certainly not part of Git's core data model, so I don't think we
> should mention that here.
>
>> +Like all other objects, commits can never be changed after they're created.
>> +For example, "amending" a commit with `git commit --amend` creates a new commit.
>> +The old commit will eventually be deleted by `git gc`.
>
> If we mention git-gc(1) I think it would make sense to use
> `linkgit:git-gc[1]` instead to provide a link to its man page.

Agreed.

>> +[[tree]]
>> +trees::
>> +    A tree is how Git represents a directory. It lists, for each item in
>> +    the tree:
>> ++
>> +1. The *permissions*, for example `100644`
>
> I think we should rather call these "mode bits". These bits are
> permissions indeed when you have a blob, but for subtrees, symlinks and
> submodules they aren't.

I think it's a bit strange to call them mode bits since I thought they were stored
as ASCII strings and it's basically an enum of 5 options, but I see your point.
I think "file mode" will work and that's used elsewhere.

I wonder if it would make sense to list all of the possible file modes if
this isn't documented anywhere else, my impression is that it's a short
list and that it's unlikely to change much in the future.

And listing them all might make it more clear that Git's file modes don't
have much in common with Unix file modes.
I looked for where this is documented and it looks like the only place is
in `man git-fast-import` . That man page says that there are just 5 options
(040000, 160000, 100644, 100755, 120000)

>> +2. The *type*: either <<blob,`blob`>> (a file), `tree` (a directory),
>> +  or <<commit,`commit`>> (a Git submodule)
>
> There's also symlinks.

I created a test symlink and it looks like symlinks are stored as type "blob".
I might say which type corresponds to which file mode,
though I'm not sure what type corresponds to the "gitlink" mode (commit?).

I think these are the 5 modes and what they mean / what type they
should have. Not sure about the gitlink mode though.

  - `100644`: regular file (with type `blob`)
  - `100755`: executable file (with type `blob`)
  - `120000`: symbolic link (with type `blob`)
  - `040000`: directory (with type `tree`)
  - `160000`: gitlink, for use with submodules (with type `commit`)

>> +3. The *object ID*
>> +4. The *filename*
>> ++
>> +For example, this is how a tree containing one directory (`src`) and one file
>> +(`README.md`) is stored:
>> ++
>> +----
>> +100644 blob 8728a858d9d21a8c78488c8b4e70e531b659141f README.md
>> +040000 tree 89b1d2e0495f66d6929f4ff76ff1bb07fc41947d src
>> +----
>> ++
>> +*NOTE:* The permissions are in the same format as UNIX permissions, but
>> +the only allowed permissions for files (blobs) are 644 and 755.
>> +
>> +[[blob]]
>> +blobs::
>> +    A blob is how Git represents a file. A blob object contains the
>> +    file's contents.
>> ++
>> +Storing a new blob for every new version of a file can get big, so
>> +`git gc` periodically compresses objects for efficiency in `.git/objects/pack`.
>
> I would claim that it's not necessary to mention object compression.
> This should be a low-level detail that users don't ever have to worry
> about. Furthermore, packing objects isn't only relevant in the context
> of blobs: trees for example also tend to compress very well as there
> typically is only small incremental updates to trees.

I discussed why I think this important in another reply,
https://lore.kernel.org/all/51e0a55c-1f1d-4cae-9459-8c2b9220e52d@app.fastmail.com/,
will paste what I said here. I'll think about this more though.

paste follows:

That's true! The reason I think this is important to mention is that I find
that people often "reject" information that they find implausible, even
if it comes from a credible source. ("that can't be true! I must be
not understanding correctly. Oh well, I'll just ignore that!")

I sometimes hear from users that "commits can't be snapshots", because
it would take up too much disk space to store every version of
every commit. So I find that sometimes explaining a little bit about the
implementation can make the information more memorable.

Certainly I'm not able to remember details that don't make sense
with my mental model of how computers work and I don't expect other
people to either, so I think it's important to give an explanation that
handles the biggest "objections".

>> +[[tag-object]]
>> +tag objects::
>> +    Tag objects (also known as "annotated tags") contain:
>> ++
>> +1. The *tagger* and tag date
>> +2. A *tag message*, similar to a commit message
>> +3. The *ID* of the object (often a commit) that they reference
>
> They can also be signed, if we want to mention that.

I guess that's true for commit objects too. Not sure whether to
mention it either, can add it if others think it's important.

>> +[[references]]
>> +REFERENCES
>> +----------
>> +
>> +References are a way to give a name to a commit.
>> +It's easier to remember "the changes I'm working on are on the `turtle`
>> +branch" than "the changes are in commit bb69721404348e".
>> +Git often uses "ref" as shorthand for "reference".
>> +
>> +References that you create are stored in the `.git/refs` directory,
>> +and Git has a few special internal references like `HEAD` that are stored
>> +in the base `.git` directory.
>
> This isn't true anymore with the introduction of the reftable backend,
> which is slated to become the default backend. I'd argue that this is
> another implementation detail that the user shouldn't have to worry
> about.

Makes sense, will fix. (as well as other references to the .git prefix and
"subdirectories").

>> +References can either be:
>> +
>> +1. References to an object ID, usually a <<commit,commit>> ID
>> +2. References to another reference. This is called a "symbolic reference".
>> +
>> +Git handles references differently based on which subdirectory of
>> +`.git/refs` they're stored in.
>
> So instead of saying "subdirectory", I'd rather say "reference
> hierarchy".
>
> In general, I think we should explain that references are layed out
> in a hierarchy. This is somewhat obvious with the "files" backend, as we
> use directories there. But as we move on to the "reftable" backend this
> may become less obvious over time.

That makes sense.

>> +[[tag]]
>> +tags: `.git/refs/tags/<name>`::
>> +    A tag is a name for a commit ID, tag object ID, or other object ID.
>> +    Tags are stored in the `refs/tags/` directory.
>> ++
>> +Even though branches and commits are both "a name for a commit ID", Git
>> +treats them very differently.
>> +Branches are expected to be regularly updated as you work on the branch,
>> +but it's expected that a tag will never change after you create it.
>
> This sounds a bit like the user itself needs to update the branch. How
> about this instead:
>
>     Even though branches and commits are both "a name for a commit ID", Git
>     treats them very differently:
>
>         - Branches can be checked out directly. If so, creating a new
>           commit will automatically update the checked-out branch to
>           point to the new commit.
>
>         - Tags cannot be checked out directly and don't move when
>           creating a new commit. Instead, one can only check out the
>           commit that a branch points to. This is called "detached
>           HEAD", and the effect is that a new commit will not update 

I think mentioning that branches can be checked out and that tags can't
is a good idea.

>> +[[HEAD]]
>> +HEAD: `.git/HEAD`::
>> +    `HEAD` is where Git stores your current <<branch,branch>>.
>> +    `HEAD` is normally a symbolic reference to your current branch, for
>> +    example `ref: refs/heads/main` if your current branch is `main`.
>> +    `HEAD` can also be a direct reference to a commit ID,
>> +    that's called "detached HEAD state".
>> +
>> +[[remote-tracking-branch]]
>> +remote tracking branches: `.git/refs/remotes/<remote>/<branch>`::
>> +    A remote-tracking branch is a name for a commit ID.
>> +    It's how Git stores the last-known state of a branch in a remote
>> +    repository. `git fetch` updates remote-tracking branches. When
>> +    `git status` says "you're up to date with origin/main", it's looking at
>> +    this.
>
> This misses "refs/remotes/<remote>/HEAD". This reference is a symbolic
> reference that indicates the default branch on the remote side.

Is "refs/remotes/<remote>/HEAD" a remote-tracking branch?
I've never thought about that reference and I'm not sure what to call it.

>> +[[other-refs]]
>> +Other references::
>> +    Git tools may create references in any subdirectory of `.git/refs`.
>> +    For example, linkgit:git-stash[1], linkgit:git-bisect[1],
>> +    and linkgit:git-notes[1] all create their own references
>> +    in `.git/refs/stash`, `.git/refs/bisect`, etc.
>> +    Third-party Git tools may also create their own references.
>> ++
>> +Git may also create references in the base `.git` directory
>> +other than `HEAD`, like `ORIG_HEAD`.
>
> Let's mention that such references are typically spelt all-uppercase
> with underscores between. You shouldn't ever create a reference that is
> for example called ".git/foo".
>
> We enforce this restriction inconsistently, only, but I don't think that
> should keep us from spelling out the common rule.

That makes sense. I'm also not sure whether third-party
Git tools are "supposed" to create references outside of "refs/",
or whether that's common. 

>> +*NOTE:* As an optimization, references may be stored as packed
>> +refs instead of in `.git/refs`. See linkgit:git-pack-refs[1].
>
> I'd drop this note. It's an internal implementation detail and only true
> for the "files" backend. The "reftable" backend stores references quite
> differently and doesn't really "pack" references.
>
>> +[[index]]
>> +THE INDEX
>> +---------
>> +
>> +The index, also known as the "staging area", contains the current staged
>
> Honestly, I always forget which of these two nouns we are supposed to
> use nowadays. I think consensus was to use "index" and avoid using
> "staging area"? Not sure though, but I think we should only mention
> one of these.
>
>> +version of every file in your Git repository. When you commit, the files
>> +in the index are used as the files in the next commit.
>> +
>> +Unlike a tree, the index is a flat list of files.
>> +Each index entry has 4 fields:
>> +
>> +1. The *permissions*
>> +2. The *<<blob,blob>> ID* of the file
>> +3. The *filename*
>> +4. The *number*. This is normally 0, but if there's a merge conflict
>
> I think we don't call this "number", but "stage".

Thanks, I see that it's sometimes called "stage number" which is a little
easier to search for so I'll call it that.

>> +   there can be multiple versions (with numbers 0, 1, 2, ..)
>> +   of the same filename in the index.
>> +
>> +It's extremely uncommon to look at the index directly: normally you'd
>> +run `git status` to see a list of changes between the index and <<HEAD,HEAD>>.
>> +But you can use `git ls-files --stage` to see the index.
>> +Here's the output of `git ls-files --stage` in a repository with 2 files:
>> +
>> +----
>> +100644 8728a858d9d21a8c78488c8b4e70e531b659141f 0 README.md
>> +100644 665c637a360874ce43bf74018768a96d2d4d219a 0 src/hello.py
>> +----
>> +
>> +[[reflogs]]
>> +REFLOGS
>> +-------
>> +
>> +Git stores the history of branch, tag, and HEAD refs in a reflog
>> +(you should read "reflog" as "ref log"). Not every ref is logged by
>> +default, but any ref can be logged.
>
> If we mention this here, do we maybe want to mention how the user can
> decide which references are logged?

Do you mean by using the setting `core.logAllRefUpdates`?

>> +Each reflog entry has:
>> +
>> +1. *Before/after *commit IDs*
>
> This will probably misformat as we have three asterisks here, not two.
>
>> +2. *User* who made the change, for example `Maya <maya@example.com>`
>> +3. *Timestamp*
>
> Suggestion: "*Timestamp* when that change has been made".

Makes sense.

>> +4. *Log message*, for example `pull: Fast-forward`
>> +
>> +Reflogs only log changes made in your local repository.
>> +They are not shared with remotes.
>
> We may want ot mention that you can reference reflog entries via
> `refs/heads/<branch>@{<reflog-nr>}`.
>
> In general, one thing that I think would be important to highlight in
> this document is revisions. Most of the commands tend to not accept
> references, but revisions instead, which are a lot more flexible. They
> use our do-what-I-mean mechanism to resolve, but also allow the user to
> specify commits relative to one another. It's probably sufficient though
> to mention them briefly and then redirect to girevisions(7).

Will think about this, I'm not sure how to best incorporate that.
Maybe under the commits section.

> Thanks for working on this!

Thanks for the review!

- Julia

> Le 7 nov. 2025 à 18:08, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> "Julia Evans" <julia@jvns.ca> writes:
> 
>> ... I do not understand in what way this rephrasing helps the
>> reader, or how you think the current phrasing might cause confusion for the
>> reader.
> 
> A branch (or any ref) does *not* *REFERENCE* an ID.  They refer to
> objects by *recording* an ID.  The distinction is not clear with
> your wording.

I concur with your later email that this is not worth delaying the rest of the document for.

My only other opinion on the matter is: what does making this distinction clear do to benefit readers of this document? I cannot come up with one, and I suspect Julia cannot either. 

Clearly you feel strongly about it, though, given the shouty caps and “I have no more words” phrasing, which I find convey a tone that is… less than welcoming. Perhaps it’s simply time to move on? And someone motivated can propose improvements.  

Ben Knoble <ben.knoble@gmail.com> writes:

> My only other opinion on the matter is: what does making this
> distinction clear do to benefit readers of this document?

I care about teaching people not just _what_ but _why_, because with
vague distinction, many tend to memorize _what_ without
understanding the reasoning behind it.  "Our object names are
computed as a hash of the contents in it formatted in a canonical
way" is "what we do to compute an object name", but the reason
behind the design is because we want to be able to dedup the same
thing cheaply, detect two objects that are different cheaply, which
is "why" in this example and it is equally, if not more, important.

The refs and objects record object names, and that is "what"; the
reason why they do so is to refer to these objects.  If somebody
comes up with other ways to uniquely refer to these objects, their
implementation of git-compatible system does not have to make their
refs record object names---they can draw a line from a circle to a
rectangle instead of writing the object name of that rectangle in
the circle---and their system is still compatible with the Git data
model at the higher/conceptual level.  IOW, what exactly is done at
the byte level (like file format) is lower part of the "data model",
but what these byte level details wants to achieve is the other,
higher half of the "data model".  A data model documentation should
teach both levels.

On Sat, Nov 8, 2025, at 11:59 PM, Junio C Hamano wrote:
> Ben Knoble <ben.knoble@gmail.com> writes:
>
>> My only other opinion on the matter is: what does making this
>> distinction clear do to benefit readers of this document?
>
> I care about teaching people not just _what_ but _why_, because with
> vague distinction, many tend to memorize _what_ without
> understanding the reasoning behind it.  "Our object names are
> computed as a hash of the contents in it formatted in a canonical
> way" is "what we do to compute an object name", but the reason
> behind the design is because we want to be able to dedup the same
> thing cheaply, detect two objects that are different cheaply, which
> is "why" in this example and it is equally, if not more, important.
>
> The refs and objects record object names, and that is "what"; the
> reason why they do so is to refer to these objects.  If somebody
> comes up with other ways to uniquely refer to these objects, their
> implementation of git-compatible system does not have to make their
> refs record object names---they can draw a line from a circle to a
> rectangle instead of writing the object name of that rectangle in
> the circle---and their system is still compatible with the Git data
> model at the higher/conceptual level.  IOW, what exactly is done at
> the byte level (like file format) is lower part of the "data model",
> but what these byte level details wants to achieve is the other,
> higher half of the "data model".  A data model documentation should
> teach both levels.

Thanks, this is exactly what I was looking for when I asked in what way
this rephrasing helps the reader. I agree that explaining the "why" is
very important.

It sounds like there are 2 "whats" and "whys" here:

#1:
what: object IDs are hashes of the contents
why: this makes it very fast to avoid storing duplicate information,
     and it's extremely fast to check if 2 objects are the same or not

I love the idea of explaining this. I think we could incorporate it very easily
by adding this paragraph in the "Objects" introduction, right before
"Here's how each type of object is structured":

    The reason the ID is a cryptographic hash is that it makes it extremely
    fast for Git to tell if 2 objects have the same contents or not
    (if they have the same ID, they have the same contents!),
    and it means Git will never store duplicate objects.

Will add that unless there are any objections.

#2:
what: The refs contain object IDs
why: to refer to the object

I think this is so obvious that going out of our way to explain it
risks confusing the reader. Spending too much time explaining something
obvious can make the reader feel like they're missing something.

I can't imagine any purpose for the refs containing object IDs other
than to refer to the object?

Like you noticed in the tag object section, I think saying that the tag
object "refers to an object" works well in that context, but in the context
of explaining what a branch is it makes the text more confusing.

"Julia Evans" <julia@jvns.ca> writes:

> Like you noticed in the tag object section, I think saying that the tag
> object "refers to an object" works well in that context, but in the context
> of explaining what a branch is it makes the text more confusing.

Sorry, but I do not understand your objection, as I cannot see what
confusion it would bring in in saying "a ref refers to an object"
(or "a branch refers to a commit object").  A ref refers to an
object, just like a tag field in a tag object or a tree-entry in a
tree object refer to another object.  They do so by recording the
name of the object they refer to.  So what's so confusing if we said
that straight?

Are you saying that the noun "reference" (or "ref") is a sufficient
clue to readers that their objective is to "refer to" something, so
"refers to" is a redundant thing to say?

Maybe its just me, but I find it a quite roundabout thing to say
that a ref refers to an object name (or "ID" if you like), simply
because name or ID *is* a way to refer to the thing that is assigned
that name, so you are making a ref to refer to something ("name")
that refers to what it ("ref") originally wanted to refer to
("object").

That is what I find the most strange in the construction "A branch
refers to ID" at the conceptual level.  I am much less unhappy with
"A branch records an ID", but stopping at that may make readers ask
the obvious question "what goal does that design aim to achieve?"
(whose answer is of course "to refer to the object that is assigned
that ID").

"A branch refers to a commit object by recording its object name",
"A branch records the ID of a commit it refers to", "A branch
records the ID of the commit at the tip of its history".  Any of the
phrasing that does not make "ID" the object/target of the verb
"refer to" would work to avoid that strange construction.

By the way, Ben used a word "unwelcome", but the words that are more
appropriate to describe my reaction were "frustrated" (for not being
able to explain what I know to be true clearly to make others
understand) and "disappointed".

> Le 11 nov. 2025 à 05:13, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> By the way, Ben used a word "unwelcome", but the words that are more
> appropriate to describe my reaction were "frustrated" (for not being
> able to explain what I know to be true clearly to make others
> understand) and "disappointed".

While that isn’t precisely my phrasing, I certainly had a similar impact. Either way, thanks for clarifying: my intent (not always the same as impact; see prior) was to point out the way such things may be perceived. 

I deeply appreciate, by way of having been in similar situations, that you were frustrated/disappointed with the conversation or yourself—language is hard! I’m glad that frustration was not directed at any contributor, and I am also hopeful that future contributors will see a maintainer who cares about contributors and clear communication and decide they should spend time on this project. That is the source of my use of the word “welcome.” :)

(this message got a bit long but the tl;dr is: maybe
"a branch is a label for a commit ID" would work?)

On Tue, Nov 11, 2025, at 5:13 AM, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
>
>> Like you noticed in the tag object section, I think saying that the tag
>> object "refers to an object" works well in that context, but in the context
>> of explaining what a branch is it makes the text more confusing.
>
> Sorry, but I do not understand your objection, as I cannot see what
> confusion it would bring in in saying "a ref refers to an object"
> (or "a branch refers to a commit object"). 

> A ref refers to an
> object, just like a tag field in a tag object or a tree-entry in a
> tree object refer to another object.  They do so by recording the
> name of the object they refer to.  So what's so confusing if we said
> that straight?

My main strategy for figuring out if something is confusing or not is
to talk to a few different users of the software and to ask them what
they think. I have a pretty empirical approach to figuring out if an
explanation is clear or not, if people think it's clear, then it's clear.
(the question of "accuracy" is separate of course)

From experience talking to people about references in Git I know
that this particular thing is extremely easy to get wrong, I used to
often try to explain branches by saying something like "A branch
to a commit" and I would get kind of a blank stare, which is why
I'm so cautious about the phrasing here.

The reason I started with "a branch is a name for a commit ID"
initially is that I've found that people respond well to that phrasing
in the past, and I don't think it gives a misleading impression about
what a branch is. But I thought your point that (in the context
of this document) the term "name" could perhaps be confused
with "object name" was reasonable, so I've been trying to
come up with an alternative.

It's always a little tricky to explain from first principles _why_
something is confusing, when I started working on explaining Git a
couple of years ago I would have thought that many of your suggested
phrasings would be an effective way to explain how Git branches work to
people and I was very surprised to see how careful I had to be around
the phrasing to get folks to understand how branches work.


> Are you saying that the noun "reference" (or "ref") is a sufficient
> clue to readers that their objective is to "refer to" something, so
> "refers to" is a redundant thing to say?
>
> Maybe its just me, but I find it a quite roundabout thing to say
> that a ref refers to an object name (or "ID" if you like), simply
> because name or ID *is* a way to refer to the thing that is assigned
> that name, so you are making a ref to refer to something ("name")
> that refers to what it ("ref") originally wanted to refer to
> ("object").

My thought process is sort of like this: I have two descriptions of
"a Git branch" that people have responded well to in the past in
practice:

1. a branch is a name for a commit ID (you said that the use of
   "name" could be confused with "object name", which
   I thought was fair)
2. a branch is a file that contains a commit ID (people often
   respond very well to how concrete this is, but it refers to
   Git's implementation which we're trying to avoid in this context)

So I'm trying to find a different wording that's similar to one of these
two phrasings that I know are effective, but that doesn't have those
problems.

Some of the options we've discussed are:

- "a branch refers to a commit ID" (which as you've said has kind of a
  "type" issue since technically the branch refers to a commit, though
  when I've discussed it people they don't seem to think it's a problem
  in practice)
- "a branch refers to a commit, using its ID" (we had a long discussion
  about how "using its ID" can lead the reader to think "wait, how else
  could you refer to a commit", which in the context of trying to learn
  what a branch is an unproductive distraction)
- "a branch records a commit ID" (from my discussions I'm pretty sure the
  word "records" does not work, I think it's because introducing a new
  verb like "records" is always a bit dangerous)

One idea I just had is "a branch is a label for a commit ID", which
I think avoids the issue with "name" from earlier.

> That is what I find the most strange in the construction "A branch
> refers to ID" at the conceptual level.  I am much less unhappy with
> "A branch records an ID", but stopping at that may make readers ask
> the obvious question "what goal does that design aim to achieve?"
> (whose answer is of course "to refer to the object that is assigned
> that ID").
>
> "A branch refers to a commit object by recording its object name",
> "A branch records the ID of a commit it refers to", "A branch
> records the ID of the commit at the tip of its history".  Any of the
> phrasing that does not make "ID" the object/target of the verb
> "refer to" would work to avoid that strange construction.
>
> By the way, Ben used a word "unwelcome", but the words that are more
> appropriate to describe my reaction were "frustrated" (for not being
> able to explain what I know to be true clearly to make others
> understand) and "disappointed".

"Julia Evans" <julia@jvns.ca> writes:

>> Maybe its just me, but I find it a quite roundabout thing to say
>> that a ref refers to an object name (or "ID" if you like), simply
>> because name or ID *is* a way to refer to the thing that is assigned
>> that name, so you are making a ref to refer to something ("name")
>> that refers to what it ("ref") originally wanted to refer to
>> ("object").
> ...
> One idea I just had is "a branch is a label for a commit ID", which
> I think avoids the issue with "name" from earlier.
>
>> That is what I find the most strange in the construction "A branch
>> refers to ID" at the conceptual level.  I am much less unhappy with
>> "A branch records an ID", but stopping at that may make readers ask
>> the obvious question "what goal does that design aim to achieve?"
>> (whose answer is of course "to refer to the object that is assigned
>> that ID").
>>
>> "A branch refers to a commit object by recording its object name",
>> "A branch records the ID of a commit it refers to", "A branch
>> records the ID of the commit at the tip of its history".  Any of the
>> phrasing that does not make "ID" the object/target of the verb
>> "refer to" would work to avoid that strange construction.

Sorry, but I am having a hard time to come up with something that I
can give to help somebody who rejects "record", saying that it is a
new verb, and in the same message introduces "label" as a better
alternative, as we haven't seen "label" used in this context,
either.

Besides, a label, a name, or an ID are all that are used to refer to
something (in this context, "a commit object"), so I find the newly
proposed one just as roundabout as "a branch refers to ID" in the
same way.  The use of *ID* is a low-level implementation detail to
make the ref work as a label for, or make the ref refer to, an
object, so "is a label for ID" is just as bad as "refers to ID".

If we do not hesitate using a new word and introduce "label", "a
branch works as a label for a commit object" may probably work,
probably.

Thanks.

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> +2. The *file type*, which must be one of these five types:
> +  - *regular file*
> +  - *executable file*
> +  - *symbolic link*
> +  - *directory*
> +  - *gitlink* (for use with submodules)
> +3. The <<object-id,*object ID*>> with the contents of the file, directory,
> +   or gitlink.
> ++
> +For example, this is how a tree containing one directory (`src`) and one file
> +(`README.md`) is stored:
> ++
> +----
> +100644 blob 8728a858d9d21a8c78488c8b4e70e531b659141f README.md
> +040000 tree 89b1d2e0495f66d6929f4ff76ff1bb07fc41947d src
> +----
> +
> +NOTE: In the output above, Git displays the file type of each tree entry
> +using a format that's loosely modelled on Unix file modes (`100644` is
> +"regular file", `100755` is "executable file", `120000` is "symbolic
> +link", `040000` is "directory", and `160000` is "gitlink"). It also
> +displays the object's type: `blob` for files and symlinks, `tree` for
> +directories, and `commit` for gitlinks.

As a description of the data model, moving the exact bit assignment
to a side note like the above hunk (relative to the previous
iteration) does make the body text less cluttered, which I think is
a welcome change.

Junio C Hamano <gitster@pobox.com> writes:

> If we do not hesitate using a new word and introduce "label", "a
> branch works as a label for a commit object" may probably work,
> probably.

Another thing.

Do we want to limit the definition of "branch" very narrowly, i.e.,
"subset of refs whose refname begins with refs/heads/"?  

Or do we want to give a description at a bit higher conceptual
level, something like:

  A branch is a mechanism to help you grow one line of history (in
  the sea/cloud of commits) by (1) keeping track of the commit it
  currently is at (by recording its ID in the ref used to implement
  the branch), (2) allowing you easily record a new commit you
  create while you are on it as a child of the current commit (by
  allowing the symbolic ref "HEAD" to point the ref used to
  implement the branch), (3) keeping the description of the theme of
  the particular line of history being developed there (by using
  "branch.<name>.description" configuration variable for the branch)
  which is incorporated when the branch gets merged to an
  integration branch, and (4) keeping track of how the branch has
  grown over time (in the reflog for the ref used to implement the
  branch).

We can limit ourselves to view a "branch" as a narrow subset of a
ref that can point at a single commit in the dag of commits, and it
can be updated at any time to point another different commit that
has no relation to the previous commit.

Once we stop limiting ourselves and explain the purpose of using a
"branch", "it can be updated to point any random commit" stops being
entirely true.  While the "git branch -f" command can be used to do
so, doing so all the time would go against what makes a branch a
branch, i.e. to keep track of the process of growing the history,
and it is expected that it would be a lot more common for the commit
pointed at by the branch ref to move by growing the history with
"git commit", refining the history with "git rebase", etc.  But that
can only follow if readers understand the branch as more than "just
a ref whose name begins with refs/heads/".

I am not sure what level the data model description you are writing
should be at.  The current description seems to concentrate too
narrowly on "a branch is a specialization of a ref" aspect, and
while it is not incorrect as a description of a building block of a
tool set to implement a workflow, it might be too limiting to form
a proper mental model.  I dunno.

On Wed, Nov 12, 2025, at 5:49 PM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> If we do not hesitate using a new word and introduce "label", "a
>> branch works as a label for a commit object" may probably work,
>> probably.
>
> Another thing.
>
> Do we want to limit the definition of "branch" very narrowly, i.e.,
> "subset of refs whose refname begins with refs/heads/"?  
>
> Or do we want to give a description at a bit higher conceptual
> level, something like:
>
>   A branch is a mechanism to help you grow one line of history (in
>   the sea/cloud of commits) by (1) keeping track of the commit it
>   currently is at (by recording its ID in the ref used to implement
>   the branch), (2) allowing you easily record a new commit you
>   create while you are on it as a child of the current commit (by
>   allowing the symbolic ref "HEAD" to point the ref used to
>   implement the branch), (3) keeping the description of the theme of
>   the particular line of history being developed there (by using
>   "branch.<name>.description" configuration variable for the branch)
>   which is incorporated when the branch gets merged to an
>   integration branch, and (4) keeping track of how the branch has
>   grown over time (in the reflog for the ref used to implement the
>   branch).
>
> We can limit ourselves to view a "branch" as a narrow subset of a
> ref that can point at a single commit in the dag of commits, and it
> can be updated at any time to point another different commit that
> has no relation to the previous commit.

I think talking too much about the intentions behind branches runs
the risk of getting into a discussion from Git workflows which IMO
is definitely out of scope for this document. For example "which is
incorporated when the branch gets merged to an integration branch" is
talking about a specific Git workflow.

From my point of view as a Git user one of Git's biggest strengths is its
flexibility; because branches _can_ be moved to point at a different
commit at any time in various ways (via `git reset --hard`, `git rebase`, or
`git commit --amend`), there's a lot of flexibility in how someone can
choose to use Git, including never using branches at all. 
(the flexibility is also one of the things that makes Git hard of course :) )

So I'd prefer to keep editorializing about what a branch "means"
to a minimum.

Right now we have this, which tries to explain a very small amount
about how branches are used that should apply to almost
all Git workflows:

"Even though branches and tags both refer to a commit ID, Git treats
them very differently. Branches are expected to change over time: when
you make a commit, Git will update your current branch to point to the
new commit. "

> Once we stop limiting ourselves and explain the purpose of using a
> "branch", "it can be updated to point any random commit" stops being
> entirely true.  While the "git branch -f" command can be used to do
> so, doing so all the time would go against what makes a branch a
> branch, i.e. to keep track of the process of growing the history,
> and it is expected that it would be a lot more common for the commit
> pointed at by the branch ref to move by growing the history with
> "git commit", refining the history with "git rebase", etc.  But that
> can only follow if readers understand the branch as more than "just
> a ref whose name begins with refs/heads/".
>
> I am not sure what level the data model description you are writing
> should be at.  The current description seems to concentrate too
> narrowly on "a branch is a specialization of a ref" aspect, and
> while it is not incorrect as a description of a building block of a
> tool set to implement a workflow, it might be too limiting to form
> a proper mental model.  I dunno.

"Julia Evans" <julia@jvns.ca> writes:

> From my point of view as a Git user one of Git's biggest strengths is its
> flexibility; because branches _can_ be moved to point at a different
> commit at any time in various ways (via `git reset --hard`, `git rebase`, or
> `git commit --amend`), there's a lot of flexibility in how someone can
> choose to use Git, including never using branches at all. 
> (the flexibility is also one of the things that makes Git hard of course :) )
>
> So I'd prefer to keep editorializing about what a branch "means"
> to a minimum.

OK.

If you go to such an extreme and make readers oblivious to what a
branch means, some of the sanity measures we have (e.g., a branch
ref will never point at anything but a commit object, not even a
commit-ish tag is allowed) would become "unnecessary nuisance" to
them.  In other words, as I hinted, it takes a delicate balancing
act.

On Thu, Nov 13, 2025, at 2:50 PM, Julia Evans wrote:
> On Wed, Nov 12, 2025, at 5:49 PM, Junio C Hamano wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> If we do not hesitate using a new word and introduce "label", "a
>>> branch works as a label for a commit object" may probably work,
>>> probably.
>>
>> Another thing.
>>
>> Do we want to limit the definition of "branch" very narrowly, i.e.,
>> "subset of refs whose refname begins with refs/heads/"?  
>>
>> Or do we want to give a description at a bit higher conceptual
>> level, something like:
>>
>>   A branch is a mechanism to help you grow one line of history (in
>>   the sea/cloud of commits) by (1) keeping track of the commit it
>>   currently is at (by recording its ID in the ref used to implement
>>   the branch), (2) allowing you easily record a new commit you
>>   create while you are on it as a child of the current commit (by
>>   allowing the symbolic ref "HEAD" to point the ref used to
>>   implement the branch), (3) keeping the description of the theme of
>>   the particular line of history being developed there (by using
>>   "branch.<name>.description" configuration variable for the branch)
>>   which is incorporated when the branch gets merged to an
>>   integration branch, and (4) keeping track of how the branch has
>>   grown over time (in the reflog for the ref used to implement the
>>   branch).
>>
>> We can limit ourselves to view a "branch" as a narrow subset of a
>> ref that can point at a single commit in the dag of commits, and it
>> can be updated at any time to point another different commit that
>> has no relation to the previous commit.
>
> I think talking too much about the intentions behind branches runs
> the risk of getting into a discussion from Git workflows which IMO
> is definitely out of scope for this document. For example "which is
> incorporated when the branch gets merged to an integration branch" is
> talking about a specific Git workflow.
>
> From my point of view as a Git user one of Git's biggest strengths is its
> flexibility; because branches _can_ be moved to point at a different
> commit at any time in various ways (via `git reset --hard`, `git rebase`, or
> `git commit --amend`), there's a lot of flexibility in how someone can
> choose to use Git, including never using branches at all. 
> (the flexibility is also one of the things that makes Git hard of course :) )
>
> So I'd prefer to keep editorializing about what a branch "means"
> to a minimum.

To immediately contradict myself a bit: after sending this I thought to
look through Mark Dominus's great blog posts about Git to see if
he has anything to say about this, and I came across this article:
https://blog.plover.com/prog/git/branches.html, called "I wish people
would stop insisting that Git branches are nothing but refs".

It reminded me that of course in Git the word "branch" often is used
to mean "a sequence of commits", for example if I make a branch called
`topic` and add 2 commits to it I might say that that "branch" is that
sequence of two commits. I think the way Dominus talks about this is
very interesting:

	The reason people say this, the disconnection is that the Git software
	doesn't have any formal representation of branches. Conceptually, the
	branch is there; the git commands just don't understand it. This is the
	most important mismatch between the conceptual model and what the Git
	software actually does.

To me the sticky point is that "the branch is these two commits" is an important
and useful concept in Git, but it doesn't really _exist_ in Git's data model,
because Git only stores a branch as a reference to a commit.

One way I've resolved this in the past is to say something like
"you can think about a branch in 3 different ways!"
https://wizardzines.com/comics/whats-a-branch/

The idea there is to talk about how a branch might be _conceptually_
"a line of development", but that Git doesn't have anything in its data
model to track what the "base" of the line of development is, so any
time you want Git to think of a branch as "these 2 commits" you need to
give it a way to determine the base.

> Right now we have this, which tries to explain a very small amount
> about how branches are used that should apply to almost
> all Git workflows:
>
> "Even though branches and tags both refer to a commit ID, Git treats
> them very differently. Branches are expected to change over time: when
> you make a commit, Git will update your current branch to point to the
> new commit. "
>
>> Once we stop limiting ourselves and explain the purpose of using a
>> "branch", "it can be updated to point any random commit" stops being
>> entirely true.  While the "git branch -f" command can be used to do
>> so, doing so all the time would go against what makes a branch a
>> branch, i.e. to keep track of the process of growing the history,
>> and it is expected that it would be a lot more common for the commit
>> pointed at by the branch ref to move by growing the history with
>> "git commit", refining the history with "git rebase", etc.  But that
>> can only follow if readers understand the branch as more than "just
>> a ref whose name begins with refs/heads/".
>>
>> I am not sure what level the data model description you are writing
>> should be at.  The current description seems to concentrate too
>> narrowly on "a branch is a specialization of a ref" aspect, and
>> while it is not incorrect as a description of a building block of a
>> tool set to implement a workflow, it might be too limiting to form
>> a proper mental model.  I dunno.

On Thu, Nov 13, 2025 at 12:19 PM Julia Evans <julia@jvns.ca> wrote:
> To immediately contradict myself a bit: after sending this I thought to
> look through Mark Dominus's great blog posts about Git to see if
> he has anything to say about this, and I came across this article:
> https://blog.plover.com/prog/git/branches.html, called "I wish people
> would stop insisting that Git branches are nothing but refs".
>
> It reminded me that of course in Git the word "branch" often is used
> to mean "a sequence of commits" ...

Yes, this is the crux of the issue: The word "branch" is ambiguous.

In Git, the *branch name* is the `refs/heads/whatever` name, and
we also have remote-tracking branch names under `refs/remotes/`.
The *branch*, however, is some ill-defined set of commits starting
from the specific commit identified by a branch name *or* any other
unique identifier, and then working backwards for some unspecified
number of steps with unspecified constraints.

Sometimes the bare term "branch" means one or another of
these various things, and sometimes it's meant to encompass
all of them...

Chris

"Julia Evans" <julia@jvns.ca> writes:

>> So I'd prefer to keep editorializing about what a branch "means"
>> to a minimum.
>
> To immediately contradict myself a bit: after sending this I thought to
> look through Mark Dominus's great blog posts about Git to see if
> he has anything to say about this ...
> The idea there is to talk about how a branch might be _conceptually_
> "a line of development", but that Git doesn't have anything in its data
> model to track what the "base" of the line of development is, so any
> time you want Git to think of a branch as "these 2 commits" you need to
> give it a way to determine the base.

Yup, that is why you need to walk a fine line between what is hard
and mechanical "bits in the system" data model, and the conceptual
goal human users build using the bits as building blocks.

Aside from that "branch" description, the rest of the document has
been polished well enough that we are quickly approaching the point
of diminishing returns, I would think.  Should we declare victory
and mark the topic for 'next' by now?

Thanks.